﻿#region Disclaimer/Info
///////////////////////////////////////////////////////////////////////////////////////////////////
// MetaCollection
// 
// MetaCollection is a system to provide a standard structure, permissions and metadata service
// for content organization.
//
// This project is hosted at Google Code at http://code.google.com/p/metacollection/
//
// This project is licensed under the BSD license.  See the License.txt file for more information.
///////////////////////////////////////////////////////////////////////////////////////////////////
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace MetaCollection.Framework
{
	/// <summary>
	/// Request Events Delegates that are registered against a <see cref="RequestHandler"/>
	/// 
	/// Each of these events represents a stage in the request pipeline that a module may implement
	/// and register against the IRequestHandler that controls the request pipeline event execution order.
	/// 
	/// The <see cref="RequestEventTypes"/> match one to one for these methods.  When a module wishes to
	/// subscribe to one of these events it must implement this interface and provide functionality in the 
	/// desired event.  The registration occurs in the <see cref="IRequestHandler.Register()"/> method with
	/// the module to be registered and the <see cref="RequestEventTypes"/> flags set to the events to bind.
	/// 
	/// A module does not have to be an IProvider to implement this interface and successfully register for events
	/// in the request pipeline.
	/// </summary>
	public interface IRequestSink
	{
		/// <summary>
		/// Called when [request start].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnRequestStart(object sender, EventArgs args);
		/// <summary>
		/// Called [before validating the request].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnBeforeValidateRequest(object sender, EventArgs args);
		/// <summary>
		/// Called when [request validate complete].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnRequestValidateComplete(object sender, EventArgs args);
		/// <summary>
		/// Called when [before path resolve].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnBeforePathResolve(object sender, EventArgs args);
		/// <summary>
		/// Called when [path resolve complete].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnPathResolveComplete(object sender, EventArgs args);
		/// <summary>
		/// Called when [before invoke request].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnBeforeInvokeRequest(object sender, EventArgs args);
		/// <summary>
		/// Called to [validate request] by the <see cref="IRequestHandler"/>
		/// </summary>
		/// <remarks>When implementing this method the module should capture any validation exceptions
		/// and place them in the <see cref="ItemContext.ExecutionException"/> field.  Any exceptions that
		/// are not part of the validation process should remain uncaught if they can not be soaked up
		/// internally.
		/// 
		/// The overall results of this method should be indicated in the <see cref="ItemContext.IsValidRequest"/>
		/// property.
		/// </remarks>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnValidateRequest(object sender, EventArgs args);
		/// <summary>
		/// Called to [resolve the path (segment)] by the <see cref="IRequestHandler"/>
		/// </summary>
		/// <remarks>When implementing this method the module should evaluate the CurrentPathSegment (and optionally
		/// any after) and set the item representing the segment into the <see cref="ItemContext.RequestItem"/>
		/// property using the <see cref="ItemContext.UpdatePathResolution"/> method.  If the item path can not
		/// be resolved then the Item Requested should be set to null and the resolution marked complete.
		///
		/// --- WARNING ---
		/// If the module is responsible for resolving the path and it fails for any reason it must null out the
		/// item and mark resolution as complete (even though it failed).  If the module ignores the error and leaves
		/// path resolution complete set to false the onPathResolve will be looped indefinately (as it is not complete).
		/// </remarks>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnPathResolve(object sender, EventArgs args);
		/// <summary>
		/// Called when [providing the item].
		/// </summary>
		/// <remarks>This method is called when the Item Providing step is reached.
		/// This event is the entry point for modifying, retrieving or deleting an item.
		/// </remarks>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnProvideItem(object sender, EventArgs args);
		/// <summary>
		/// Called when [provide resource].
		/// </summary>
		/// <remarks>This method is called when the Provide Resource step is reached.  Providers are responsible
		/// for determining if setting or providing a resource is needed as dictated by request type
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnProvideResource(object sender, EventArgs args);
		/// <summary>
		/// Called when [handler disposing].
		/// </summary>
		/// <param name="sender">The sender.</param>
		/// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
		void OnHandlerDisposing(object sender, EventArgs args);
        /// <summary>
        /// Called when [request complete].
        /// </summary>
        /// <param name="sender">The sender.</param>
        /// <param name="args">The <see cref="System.EventArgs"/> instance containing the event data.</param>
        void OnRequestComplete(object sender, EventArgs args);
	}
}
